home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / pc / 2924.ZIP / DMLXREF.ARC / STRG.DOC < prev    next >
Encoding:
Text File  |  1988-12-28  |  13.3 KB  |  525 lines
  1. .KF:strg.toc
  2. .R:E
  3. .W:96
  4. .H:...DML STRG UNIT Version 1.00...
  5. .H:...$$Day Mon D, YEAR$$  $$Z:MI A.M.$$     Page $$$...
  6. .H:
  7. .F:
  8. .F:... Copyright (c) 1989, by DML Software Inc. ...
  9. .X:8
  10.  
  11. .K:STRING ROUTINES - CHANGES HIGHLIGHTS (VERSION 1.00)
  12. STRING ROUTINES - CHANGES HIGHLIGHTS  (VERSION 1.00)
  13.  
  14. 1/1/89 Initial Release
  15.  
  16.   
  17.  
  18. .K:1) GENERAL PURPOSE STRING
  19. 1) GENERAL PURPOSE STRING
  20.  
  21.   NAME
  22. .K:StrConstants
  23.      StrConstants
  24.  
  25.   SYNOPSIS
  26.      The constants defined here are for use with the string conversion
  27.      routines.  Each constant has two names: a long, descriptive name and a 
  28.      short name.
  29.  
  30.   DESCRIPTION
  31.  
  32.      Constant Name   Alt Name Meanings
  33.      -------------   -------- ------------------------------------------------
  34.      S_IgnoreQuoted     (S_I) Do not process characters within quotes (' or ")
  35.      S_AllSpaces        (S_A) Strip all spaces and tabs
  36.      S_Leading          (S_L) Strip all leading spaces and tabs
  37.      S_Trailing         (S_T) Strip all trailing spaces and tabs
  38.      S_ReduceToOneSpace (S_R) Reduce all spaces and tabs to one space
  39.      S_ToUpper          (S_U) Convert lower case letters to upper case
  40.      S_ToLower          (S_D) Convert upper case letters to lower case
  41.  
  42.   SEE ALSO
  43.      Strip, StrCase
  44.  
  45.   DEPENDS ON
  46.  
  47.   DIAGNOSTICS
  48.  
  49.   KNOWN RESTRICTIONS
  50.  
  51.   PARTIALLY OBSOLETED BY 
  52.  
  53.   UPDATE HISTORY
  54.  
  55.   
  56.  
  57.   NAME
  58. .K:RJS - Right Justify String
  59.      RJS - Right Justify String
  60.  
  61.   SYNOPSIS
  62.      FUNCTION RJS (Source: STRING; Size : BYTE) : STRING;
  63.  
  64.      WRITELN (RJS ('Right', 40));
  65.  
  66.  
  67.   DESCRIPTION
  68.      Returns a string preceeded by enough spaces to pad the result to the
  69.      size parameter.
  70.  
  71.   SEE ALSO
  72.      CJS - Center Justify String, LJS - Left Justify String
  73.  
  74.   DEPENDS ON
  75.  
  76.   DIAGNOSTICS
  77.      If the length of the source string is longer than the Size parameter a
  78.      "^" will be added to the result indicating that the field has
  79.      overflowed.
  80.  
  81.   KNOWN RESTRICTIONS
  82.  
  83.   PARTIALLY OBSOLETED BY 
  84.  
  85.   UPDATE HISTORY
  86.  
  87.   
  88.  
  89.   NAME
  90. .K:LJS - Left Justify String
  91.      LJS - Left Justify String
  92.  
  93.   SYNOPSIS
  94.      FUNCTION LJS (Source : STRING; Size : BYTE) : STRING;
  95.  
  96.      WRITELN (LJS ('Left', 40));
  97.  
  98.   DESCRIPTION
  99.      Returns the Source string followed by spaces to pad the string to the
  100.      Size parameter.
  101.  
  102.   SEE ALSO
  103.      CJS - Center Justify String, RJS - Right Justify String
  104.  
  105.   DEPENDS ON
  106.  
  107.   DIAGNOSTICS
  108.      If the Source string is longer than the Size parameter a "^" character
  109.      will be returned indicating that the field has overflowed.
  110.  
  111.   KNOWN RESTRICTIONS
  112.  
  113.   PARTIALLY OBSOLETED BY 
  114.  
  115.   UPDATE HISTORY
  116.  
  117.   
  118.  
  119.   NAME
  120. .K:CJS - Center Justify String
  121.      CJS - Center Justify String
  122.  
  123.   SYNOPSIS
  124.      FUNCTION CJS (Source: STRING; Size : BYTE) : STRING;
  125.  
  126.      WRITELN (CJS ('Hello', 80));
  127.  
  128.   DESCRIPTION
  129.      Places the Source string in the center of a string Size characters
  130.      long.
  131.  
  132.   SEE ALSO
  133.      RJS - Right Justify String, LJS - Left Justify String
  134.  
  135.   DEPENDS ON
  136.  
  137.   DIAGNOSTICS
  138.      If the Source string is longer than the Size variable, as much of the
  139.      source will be returned with a "^" character indicating field
  140.      overflow.
  141.  
  142.   KNOWN RESTRICTIONS
  143.  
  144.   PARTIALLY OBSOLETED BY 
  145.  
  146.   UPDATE HISTORY
  147.  
  148.   
  149.  
  150.   NAME
  151. .K:Strip - Removes blanks and tabs from a string.
  152.      Strip - Removes blanks and tabs from a string.
  153.  
  154.   SYNOPSIS
  155.      FUNCTION Strip (Source : STRING; Code : BYTE) : STRING;
  156.  
  157.      WRITELN ('>'+Strip ('   Hello  this is    nice.   '),S_AllSpaces)+'<');
  158.      displays: >Hellothisisnice.<
  159.  
  160.      WRITELN ('>'+Strip ('   Hello  this is    nice.   '),S_Leading)+'<');
  161.      displays: >Hello  this is    nice.   <
  162.  
  163.      WRITELN ('>'+Strip ('   Hello  this is    nice.   '),
  164.                                                   S_Leading+S_Trailing)+'<');
  165.      displays: >Hello  this is    nice.<
  166.  
  167.      WRITELN ('>'+Strip ('   Hello  this is    nice.   '),
  168.                                                   S_ReduceToOneSpace+'<');
  169.      displays:  > Hello this is nice. <
  170.  
  171.      To remove the leading and trailing spaces from the last example, you
  172.      must combine S_ReduceToOneSpace with S_Leading and S_Trailing.
  173.  
  174.   DESCRIPTION
  175.      Removes blanks (i.e. space characters) and tab characters from a
  176.      string and returns the result.  The original string is not altered.
  177.      The second parameter, Code, determines the blanks to strip.  Constant
  178.      values have been defined for the following functions.  Note that it is
  179.      possible to combine several functions into the same call by adding the
  180.      values of the constants together.  For example, S_Leading+S_Trailing
  181.      will strip both leading and trailing blanks.  They are processed in
  182.      the order shown below.
  183.  
  184.      Constant Name        Meanings
  185.      -------------        ------------------------------------------------
  186.      S_IgnoreQuoted       Do not process characters within quotes (' or ")
  187.      S_AllSpaces          Strip all spaces and tabs
  188.      S_Leading            Strip all leading spaces and tabs
  189.      S_Trailing           Strip all trailing spaces and tabs
  190.      S_ReduceToOneSpace   Reduce all spaces and tabs to one space
  191.  
  192.   SEE ALSO
  193.      StrCase
  194.  
  195. 
  196.  
  197.   DEPENDS ON
  198.  
  199.   DIAGNOSTICS
  200.  
  201.   KNOWN RESTRICTIONS
  202.  
  203.   PARTIALLY OBSOLETED BY 
  204.  
  205.   UPDATE HISTORY
  206.  
  207.   
  208.  
  209.   NAME
  210. .K:StrCase - Converts the case of all letters in a string.
  211.     StrCase - Converts the case of all letters in a string.
  212.  
  213.   SYNOPSIS
  214.      FUNCTION StrCase (Source : STRING; Code : BYTE) : STRING;
  215.  
  216.      WRITELN (StrCase ('uppercase', S_ToUpper));
  217.  
  218.   DESCRIPTION
  219.      Conversion of case is done using the following codes.  Note that
  220.      Constants are defined for S_IgnoreQuoted - 16, S_ToUpper - 32, and
  221.      S_ToLower - 64.
  222.  
  223.      Code    String Conversion
  224.      ----    -------------------------------------------
  225.       16     Characters enclosed in quotes are not to be
  226.              altered during string conversion.
  227.       32     Convert all characters to upper case.
  228.       64     Convert all characters to lower case.
  229.  
  230.      Code can be any combination of the above values, even though some
  231.      combinations are logically inconsistent.  Any ambiguity is resolved by
  232.      executing the conversion request codes in numerical order.  The only
  233.      exception is that code 16 (do not alter quoted strings) is always
  234.      checked.
  235.  
  236.   SEE ALSO
  237.      Strip
  238.  
  239.   DEPENDS ON
  240.  
  241.   DIAGNOSTICS
  242.  
  243.   KNOWN RESTRICTIONS
  244.  
  245.   PARTIALLY OBSOLETED BY 
  246.  
  247.   UPDATE HISTORY
  248.  
  249.   
  250.  
  251.   NAME
  252. .K:StrField - Returns a field from a delimited string.
  253.     StrField - Returns a field from a delimited string.
  254.  
  255.   SYNOPSIS
  256.      FUNCTION StrField (Source : STRING; Delimiter : CHAR; Num : BYTE) : STRING;
  257.  
  258.      WRITELN ('>'+StrField ('NumOne,NumTwo,NumThree', ',', 2)+'<');
  259.      displays: >NumTwo<
  260.  
  261.   DESCRIPTION
  262.      Returns the string field (i.e. substring) between the delimiter
  263.      characters.  Num is used to indicate that the substring starts after
  264.      the Num-1 delimiter.  This routine will only return one field per
  265.      call.  The delimiter characters are NOT returned.  If you ask for the
  266.      first field and the delimiter is not found, the entire source string
  267.      is returned.  If you ask for the second field and the delimiter is not
  268.      found, then the null field is returned.
  269.  
  270.   SEE ALSO
  271.  
  272.   DEPENDS ON
  273.  
  274.   DIAGNOSTICS
  275.  
  276.   KNOWN RESTRICTIONS
  277.  
  278.   PARTIALLY OBSOLETED BY 
  279.  
  280.   UPDATE HISTORY
  281.  
  282.   
  283.  
  284.   NAME
  285. .K:StrFill - Fill a string with a character.
  286.      StrFill - Fill a string with a character.
  287.  
  288.   SYNOPSIS
  289.      FUNCTION StrFill (FillCh : CHAR; Num : BYTE) : STRING;
  290.  
  291.      WRITELN (StrFill ('*', 80);
  292.  
  293.   DESCRIPTION
  294.      The first parameter specifies the character, and the second specifies
  295.      the length of the returned string.
  296.  
  297.   SEE ALSO
  298.  
  299.   DEPENDS ON
  300.  
  301.   DIAGNOSTICS
  302.  
  303.   KNOWN RESTRICTIONS
  304.  
  305.   PARTIALLY OBSOLETED BY 
  306.  
  307.   UPDATE HISTORY
  308.  
  309.   
  310.  
  311.   NAME
  312. .K:StrPad - Blank pad a string.
  313.      StrPad- Blank pad a string.
  314.  
  315.   SYNOPSIS
  316.      FUNCTION StrPad (Source : STRING) : STRING;
  317.  
  318.      Str1 := StrPad(Str1);
  319.  
  320.   DESCRIPTION
  321.      This function pads a string with blanks (spaces).  It is similar to right 
  322.      justifying a string, except the length is implicit; the size of the 
  323.      result field actually determines the number of blanks padded.
  324.  
  325.   SEE ALSO
  326.  
  327.   DEPENDS ON
  328.  
  329.   DIAGNOSTICS
  330.  
  331.   KNOWN RESTRICTIONS
  332.  
  333.   PARTIALLY OBSOLETED BY 
  334.  
  335.   UPDATE HISTORY
  336.  
  337.   
  338.  
  339.   NAME
  340. .K:StrShiftLeft - Shift a string left one character.
  341.      StrShiftLeft - Shift a string left one character.
  342.  
  343.   SYNOPSIS
  344.      FUNCTION StrShiftLeft (Fld : STRING; Posit : BYTE) : STRING;
  345.  
  346.      Str1 := StrShiftLeft('ABCDEFGHIJKLMNOPQRSTUVWXYZ',13);
  347.  
  348.   DESCRIPTION
  349.      This function removes a single character, whose position is specified by 
  350.      the second parameter from the string specified by the first parameter.  
  351.      The resulting string is one character longer than the original string. 
  352.      This function avoids having to code two COPY statements to achieve the 
  353.      same result. 
  354.  
  355.   SEE ALSO
  356.  
  357.   DEPENDS ON
  358.  
  359.   DIAGNOSTICS
  360.  
  361.   KNOWN RESTRICTIONS
  362.  
  363.   PARTIALLY OBSOLETED BY 
  364.  
  365.   UPDATE HISTORY
  366.  
  367.   
  368.  
  369.   NAME
  370. .K:StrShiftRight - Shift a string right one character.
  371.      StrShiftRight - Shift a string right one character.
  372.  
  373.   SYNOPSIS
  374.      FUNCTION StrShiftRight (Fld : STRING; Posit : BYTE; Fill : CHAR) : STRING;
  375.  
  376.      Str1 := StrShiftLeft(Str1,13,'M');
  377.  
  378.   DESCRIPTION
  379.      This function inserts a single character into the 'middle' of a string.  
  380.      The 'rest' of the string is shifted right one character position.  The 
  381.      first parameter specifies the string, the second the position into which 
  382.      the third parameter will be placed.  The resulting string is one 
  383.      character longer than the original string. This function avoids having to 
  384.      code two COPY statements to achieve the same result. 
  385.  
  386.   SEE ALSO
  387.  
  388.   DEPENDS ON
  389.  
  390.   DIAGNOSTICS
  391.  
  392.   KNOWN RESTRICTIONS
  393.  
  394.   PARTIALLY OBSOLETED BY 
  395.  
  396.   UPDATE HISTORY
  397.  
  398.   
  399.  
  400. .K:2) STRING CONVERSION
  401. 2) STRING CONVERSION
  402.  
  403.   NAME
  404. .K:S2C - Convert a String into a Character Array.
  405.      S2C - Convert a String into a Character Array.
  406.  
  407.   SYNOPSIS
  408.      PROCEDURE S2C (Strg : STRING ; VAR CharA ; Len : BYTE);
  409.  
  410.      S2C (MyString,MyCharArray,LENGTH(MyCharArray));
  411.  
  412.   DESCRIPTION
  413.      This routine strips out the length byte of a string, and transfers all 
  414.      the remaining used bytes of the string to an array of characters.  The 
  415.      character array is blank padded to the length specified by the length 
  416.      parameter, up to 255 bytes.  If the length parameter specifies a length 
  417.      greater than the actual character array, following bytes in memory will be
  418.      clobbered.  This routine is useful for transfering Turbo strings to DBMSs, 
  419.      etc., that only support character arrays. 
  420.  
  421.   SEE ALSO
  422.  
  423.   DEPENDS ON
  424.  
  425.   DIAGNOSTICS
  426.  
  427.   KNOWN RESTRICTIONS
  428.  
  429.   PARTIALLY OBSOLETED BY 
  430.  
  431.   UPDATE HISTORY
  432.  
  433.   
  434.  
  435.   NAME
  436. .K:C2S - Coverts a character array to a string.
  437.      C2S - Coverts a character array to a string.
  438.  
  439.   SYNOPSIS
  440.      FUNCTION C2S (VAR CharA ; Len : BYTE) : STRING;
  441.  
  442.      MyString := C2S (MyCharArray,SIZEOF(MyCharArray));
  443.  
  444.   DESCRIPTION
  445.      This routine transfers bytes from the character array to the string. The 
  446.      number of bytes transfered is specified by the length parameter up to 255 
  447.      bytes; the string length byte is set to this parameter.  This routine is 
  448.      useful for reading text import files of fixed length character fields.
  449.  
  450.   SEE ALSO
  451.  
  452.   DEPENDS ON
  453.  
  454.   DIAGNOSTICS
  455.  
  456.   KNOWN RESTRICTIONS
  457.  
  458.   PARTIALLY OBSOLETED BY 
  459.  
  460.   UPDATE HISTORY
  461.  
  462.   
  463.  
  464.   NAME
  465. .K:S2Z - Convert a string in a DOS AsciiZ string.
  466.     S2Z - Convert a string in a DOS AsciiZ string.
  467.  
  468.   SYNOPSIS
  469.      PROCEDURE S2Z (Strg : STRING ; VAR CharA); 
  470.  
  471.      S2Z (MyString,MyCharArray); 
  472.  
  473.   DESCRIPTION
  474.      This routine strips out the length byte of a string, transfers all the 
  475.      remaining used bytes of the string to an array of characters, and 
  476.      terminates the used portion of the character array with a zero byte.  If 
  477.      the actual character array isn't large enough to hold the AsciiZ string, 
  478.      following bytes in memory will be clobbered.  This routine is useful for 
  479.      using DOS file handling routines directly. 
  480.  
  481.   SEE ALSO
  482.  
  483.   DEPENDS ON
  484.  
  485.   DIAGNOSTICS
  486.  
  487.   KNOWN RESTRICTIONS
  488.  
  489.   PARTIALLY OBSOLETED BY 
  490.  
  491.   UPDATE HISTORY
  492.  
  493.   
  494.  
  495.   NAME
  496. .K:Z2S - Convert an AsciiZ string to a string.
  497.      Z2S - Convert an AsciiZ string to a string.
  498.  
  499.   SYNOPSIS
  500.      FUNCTION Z2S (VAR CharA) : STRING; 
  501.  
  502.      MyString := Z2S (MyCharArray);
  503.  
  504.   DESCRIPTION
  505.      This routine transfers bytes from the character array to the string. The 
  506.      number of bytes transfered is determine by the zero byte terminating the 
  507.      character array, or 255 bytes transfered, whichever occurs first.  the 
  508.      string length byte is set to the number of bytes transfered.
  509.  
  510.   SEE ALSO
  511.  
  512.   DEPENDS ON
  513.  
  514.   DIAGNOSTICS
  515.  
  516.   KNOWN RESTRICTIONS
  517.  
  518.   PARTIALLY OBSOLETED BY 
  519.  
  520.   UPDATE HISTORY
  521.  
  522.  
  523. 
  524.  
  525.